home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / demos / GL / libdemo / spaced.h < prev    next >
C/C++ Source or Header  |  1994-08-01  |  7KB  |  201 lines
  1. /*
  2.  * Copyright 1991, 1992, 1993, 1994, Silicon Graphics, Inc.
  3.  * All Rights Reserved.
  4.  *
  5.  * This is UNPUBLISHED PROPRIETARY SOURCE CODE of Silicon Graphics, Inc.;
  6.  * the contents of this file may not be disclosed to third parties, copied or
  7.  * duplicated in any form, in whole or in part, without the prior written
  8.  * permission of Silicon Graphics, Inc.
  9.  *
  10.  * RESTRICTED RIGHTS LEGEND:
  11.  * Use, duplication or disclosure by the Government is subject to restrictions
  12.  * as set forth in subdivision (c)(1)(ii) of the Rights in Technical Data
  13.  * and Computer Software clause at DFARS 252.227-7013, and/or in similar or
  14.  * successor clauses in the FAR, DOD or NASA FAR Supplement. Unpublished -
  15.  * rights reserved under the Copyright Laws of the United States.
  16.  */
  17. /******************************************************************************
  18. Spaced: The Three-D Space Editor
  19.  
  20. These routines provide a rather bizarre but surprisingly intuitive way 
  21.    to move a point in three dimensions using a two dimensional mouse.
  22.    It works by projecting a set of axes into two-d screen space, then
  23.    determining where within those projected axes the mouse is. The
  24.    projected axes will divide the screen into six pie pieces. If for
  25.    example, the mouse is between the projected versions of the
  26.    positive X and positive Z axis, the point being moved will follow
  27.    the mouse with its motion constrained to the X-Z plane.
  28.  
  29. To make things even simpler, holding the shift key will constrain
  30.    motion to one axis, instead of a plane. The shift key may be
  31.    pressed after unconstrained motion has begun. Motion is contrained
  32.    to the axis closest to the cursor. Similary, the alt key will constrain
  33.    motion to a plane.
  34.  
  35. It sounds funny, but it works really well. Try the example program to see for
  36.    yourself. Just type "spaced". The window shows a view volume filled
  37.    with control points. Use the left mouse button to select and move
  38.    one of the control points. Use the middle mouse button to rotate
  39.    the view volume. Try using the shift key to constrain motion.
  40.  
  41.  
  42. *****************************
  43. HOOKING IT UP TO YOUR PROGRAM
  44. *****************************
  45.  
  46. Using Spaced from a program is very simple. You only need to pass it
  47.    a matrix, a point, and some limits.
  48.  
  49. Once you know what point you will be moving, make a call to
  50. void start_spaced(void);
  51.  
  52. Everytime you want to update that point's position, call
  53. int spaced(Matrix M, Coord origin[3], Coord limit[3][2]);
  54.  
  55. M contains the matrix that gets your point from world space to
  56.    screen space. In single matrix mode, this is simply the matrix on
  57.    the top of the matrix stack at the time you would normally display 
  58.    your object (use getmatrix()). In double matrix
  59.    mode, this is the matrix which result from multiplying the viewing
  60.    matrix by the projection matrix.
  61.  
  62. origin is the coordinates of the point that will be moved. If you are
  63.    moving an object, this is the origin of your object, in world
  64.    coordinates, or whatever other convienient thing you may want to do with it.
  65.  
  66. limit specifies the bounding box, in 3D world coordinates, that you
  67.    want motion constrained to. Your bounding box can be really big, but
  68.    you must specify something. Also, be certain that the origin
  69.    initially is within the bounding box that you specify, otherwise
  70.    Spaced will freak out.
  71.    
  72.    The format is limit[x=0, y=1, z=2][lo=0,hi=1]
  73.  
  74.    For example, if you want motion to stay within a -1.0 to 1.0 cube, say
  75.    Coord limit[3][2] =
  76.     {    { -1.0, 1.0},
  77.         { -1.0, 1.0},
  78.         { -1.0, 1.0}
  79.     };
  80.  
  81. the integer it returns describes which axis or plane the user is constraining
  82.     motion to. The value will be SP_NONE, SP_X_AXIS, ..., SP_XY_PLANE, etc.
  83.  
  84. Simply set up your event processing to repeatedly call spaced() for as
  85.    long as you want to modify the contents of origin.
  86.  
  87. When motion of your point is completed to your satisfaction, call
  88.    end_spaced();
  89.  
  90. At any time, call 
  91.     void set_spaced(
  92.         int col_thresh,
  93.         int const_thresh,
  94.         Device line1,
  95.         Device line2,
  96.         Device plane1,
  97.         Device plane2);
  98.    to change Spaced's default setup values. If you want to permanently change
  99.    the defaults, edit the #define's at the bottom of this file. The meaning
  100.    of these arguments is desribed next.
  101.  
  102. ****************
  103. SETUP PARAMETERS
  104. ****************
  105.  
  106. The colinearity threshhold specifies, in pixels, when to start ignoring
  107.    axes.  In some views of your axes, you will see that two axes will come
  108.    close to being colinear.  When two axes come within the threshhold
  109.    pixels of being colinear, the shorter of the two will be ignored.
  110.  
  111. Also, axes may become very small if you are looking right down them.
  112.    The colinear threshold will cause small axes to be ignored, since a small
  113.    axis may come within col_thresh pixels of being colinear with
  114.    the other axes.
  115.  
  116. The moral: If things start acting wierd, play with the colinear
  117.    threshold.
  118.  
  119. The constrint threshhold specifies how many pixels away from the initial
  120.    position the mouse should be before we start doing constrained motion.
  121.    This insures that the point is moved where the user really wanted it to.
  122.    Increase it to be more sure; decrease to have motion start happening
  123.    more quickly.
  124.  
  125. By default, either shift key constrains motion to a line, and either alt key
  126.    constrains motion to a plane. However, you can use any button device(s)
  127.    you like. Notice that there are two devices for each type of
  128.    constraining to allow for duplicate keyboard keys (like left and right
  129.    shift keys). If you want to use only one device, use it for both
  130.    parameters. To reset any of the parameters to their default values,
  131.    use SP_DEFAULT as an argument.
  132.    
  133.    
  134. *****
  135. HINTS
  136. *****
  137.  
  138. Typically, you will want to draw the axes through the point of motion
  139.    within you bounding box. Without them, it is very hard to see what
  140.    is going on.
  141.  
  142. You may want to depth cue your axes or even your objects to give the
  143.    user a little better feel for what is happening.
  144.  
  145. Use the return value for more user hints, such as displaying the plane
  146.    that motion is contrained to in a different color.
  147.  
  148.    
  149. ***************************
  150. OTHER BUGS, COMMENTS, SUGGESTIONS
  151. ***************************
  152.  
  153. Please send them to:
  154.  
  155. Howard Look
  156. howardl@sgi.com
  157. 335-1780
  158.  
  159. Version 1.1: April 22, 1990
  160. *************************************************************************/
  161.  
  162. #define SP_COLINEAR_THRESHOLD 20
  163.  
  164. #define SP_CONSTRAINT_THRESHOLD 10
  165.  
  166. #define SP_LINE_BUTTON1 LEFTSHIFTKEY
  167. #define SP_LINE_BUTTON2 RIGHTSHIFTKEY
  168.  
  169. #define SP_PLANE_BUTTON1 LEFTALTKEY
  170. #define SP_PLANE_BUTTON2 RIGHTALTKEY
  171.  
  172. #define SP_DEFAULT -1
  173.  
  174. #define SP_NONE -1
  175. #define SP_X_AXIS 1
  176. #define SP_Y_AXIS 2
  177. #define SP_Z_AXIS 3
  178. #define SP_XY_PLANE 4
  179. #define SP_XZ_PLANE 5
  180. #define SP_YZ_PLANE 6
  181.  
  182. /* prototypes for your files */
  183. extern void start_spaced();
  184.  
  185. extern int spaced(
  186.     Matrix, 
  187.     Coord origin[3], 
  188.     Coord limit[3][2]);
  189.  
  190.     
  191. extern void end_spaced(void);
  192.  
  193. extern void set_spaced(
  194.     int col_thresh,
  195.     int const_thresh,
  196.     Device line1,
  197.     Device line2,
  198.     Device plane1,
  199.     Device plane2);
  200.     
  201.